.TH std::ranges::iota,std::ranges::iota_result 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::ranges::iota,std::ranges::iota_result \- std::ranges::iota,std::ranges::iota_result

.SH Synopsis
   Defined in header <numeric>
   Call signature
   template< std::input_or_output_iterator O, std::sentinel_for<O> S,

             std::weakly_incrementable T >
   requires std::indirectly_writable<O, const T&>                     \fB(1)\fP (since C++23)
   constexpr iota_result<O, T>

       iota( O first, S last, T value );
   template< std::weakly_incrementable T, ranges::output_range<const
   T&> R >
                                                                      \fB(2)\fP (since C++23)
   constexpr iota_result<ranges::borrowed_iterator_t<R>, T>

       iota( R&& r, T value );
.SH Helper types
   template< class O, class T >                                       \fB(3)\fP (since C++23)
   using iota_result = ranges::out_value_result<O, T>;

   Fills the range [first, last) with sequentially increasing values, starting with
   value and repetitively evaluating ++value.

   Equivalent operation:

 *(first)     = value;
 *(first + 1) = ++value;
 *(first + 2) = ++value;
 *(first + 3) = ++value;
 ...

.SH Parameters

   first, last - the range of elements to fill with sequentially increasing values
                 starting with value
   value       - initial value to store; the expression ++value must be well-formed

.SH Return value

   {last, value + ranges::distance(first, last)}

.SH Complexity

   Exactly last - first increments and assignments.

.SH Possible implementation

   struct iota_fn
   {
       template<std::input_or_output_iterator O, std::sentinel_for<O> S,
               std::weakly_incrementable T>
       requires std::indirectly_writable<O, const T&>
       constexpr iota_result<O, T> operator()(O first, S last, T value) const
       {
           while (first != last)
           {
               *first = as_const(value);
               ++first;
               ++value;
           }
           return {std::move(first), std::move(value)};
       }

       template<std::weakly_incrementable T, std::ranges::output_range<const T&> R>
       constexpr iota_result<std::ranges::borrowed_iterator_t<R>, T>
       operator()(R&& r, T value) const
       {
           return (*this)(std::ranges::begin(r), std::ranges::end(r), std::move(value));
       }
   };

   inline constexpr iota_fn iota;

.SH Notes

   The function is named after the integer function ⍳ from the programming language
   APL.

    Feature-test macro    Value    Std        Feature
   __cpp_lib_ranges_iota 202202L (C++23) std::ranges::iota

.SH Example

   Uses the vector of iterators (std::vector<std::list<T>::iterator>) as a proxy to
   shuffle the elements of the std::list, because ranges::shuffle cannot be applied to
   the std::list directly.


// Run this code

 #include <algorithm>
 #include <functional>
 #include <iostream>
 #include <list>
 #include <numeric>
 #include <random>
 #include <vector>

 template <typename Proj = std::identity>
 void println(auto comment, std::ranges::input_range auto&& range, Proj proj = {})
 {
     for (std::cout << comment; auto const &element : range)
         std::cout << proj(element) << ' ';
     std::cout << '\\n';
 }

 int main()
 {
     std::list<int> list(8);

     // Fill the list with ascending values: 0, 1, 2, ..., 7
     std::ranges::iota(list, 0);
     println("List: ", list);

     // A vector of iterators (see the comment to Example)
     std::vector<std::list<int>::iterator> vec(list.size());

     // Fill with iterators to consecutive list's elements
     std::ranges::iota(vec.begin(), vec.end(), list.begin());

     std::ranges::shuffle(vec, std::mt19937 {std::random_device {}()});
     println("List viewed via vector: ", vec, [](auto it) { return *it; });
 }

.SH Possible output:

 List: 0 1 2 3 4 5 6 7
 List viewed via vector: 5 7 6 0 1 3 4 2

.SH See also

   fill              copy-assigns the given value to every element in a range
                     \fI(function template)\fP
   ranges::fill      assigns a range of elements a certain value
   (C++20)           (niebloid)
                     assigns the results of successive function calls to every element
   generate          in a range
                     \fI(function template)\fP
   ranges::generate  saves the result of a function in a range
   (C++20)           (niebloid)
   ranges::iota_view a view consisting of a sequence generated by repeatedly
   views::iota       incrementing an initial value
   (C++20)           \fI(class template)\fP (customization point object)
   iota              fills a range with successive increments of the starting value
   \fI(C++11)\fP           \fI(function template)\fP
